<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
<!-- winrt.qdoc -->
  <title>Qt for UWP | Qt 5.14</title>
  <link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
  <script type="text/javascript">
    document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
    // loading style sheet breaks anchors that were jumped to before
    // so force jumping to anchor again
    setTimeout(function() {
        var anchor = location.hash;
        // need to jump to different anchor first (e.g. none)
        location.hash = "#";
        setTimeout(function() {
            location.hash = anchor;
        }, 0);
    }, 0);
  </script>
</head>
<body>
<div class="header" id="qtdocheader">
  <div class="main">
    <div class="main-rounded">
      <div class="navigationbar">
        <table><tr>
<td ><a href="index.html">Qt 5.14</a></td><td >Qt for UWP</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.14.2 Reference Documentation</td>
        </tr></table>
      </div>
    </div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#supported-configurations">Supported Configurations</a></li>
<li class="level1"><a href="#requirements">Requirements</a></li>
<li class="level1"><a href="#getting-started">Getting Started</a></li>
<li class="level2"><a href="#notes-to-desktop-users">Notes to Desktop Users</a></li>
<li class="level2"><a href="#building-applications">Building Applications</a></li>
<li class="level1"><a href="#building-from-source">Building from Source</a></li>
<li class="level1"><a href="#running-applications-from-command-line">Running Applications from Command Line</a></li>
<li class="level2"><a href="#package-content">Package Content</a></li>
<li class="level2"><a href="#winrt-runner-tool">WinRT Runner Tool</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt for UWP</h1>
<span class="subtitle"></span>
<!-- $$$winrt_support.html-description -->
<div class="descr"> <a name="details"></a>
<p>Qt for UWP allows you to run Qt applications on devices supporting the Universal Windows Platform (UWP). Microsoft Windows 10 introduced UWP, which provides a common application platform on every device that runs Windows 10, as a successor to Windows Runtime (WinRT) introduced by Windows 8. The UWP core APIs are the same on all Windows devices, and therefore applications that only use the core APIs will run on any Windows 10 device, such as a desktop PC, or Xbox One.</p>
<p>The Qt port was originally written for WinRT and updated to support UWP. The port uses the C++ capabilities. While UWP supports the component extensions internally, they are not used inside Qt and you do not need to use them. UWP applications run in a sandboxed environment for security reasons and support different architectures, such as ARM and x86.</p>
<a name="winrt-supported-configurations"></a><a name="supported-configurations"></a>
<h2 id="supported-configurations">Supported Configurations</h2>
<p>The following configurations are supported.</p>
<div class="table"><table class="generic" width="80%">
 <thead><tr class="qt-style"><th >Platform Version</th><th >Architecture</th><th >Compiler</th><th >Build Environment</th></tr></thead>
<tr valign="top" class="odd"><td >Universal Windows Platform 10</td><td ><code>x86</code>, <code>x86_64</code>, and <code>armv7</code></td><td ><b>MSVC 2017</b>, <b>MSVC 2015</b></td><td ><b>Windows 10</b></td></tr>
</table></div>
<p><br />
Universal Windows Platforms include Windows 10, Windows 10 IoT devices, Xbox One, and HoloLens.</p>
<a name="requirements"></a>
<h2 id="requirements">Requirements</h2>
<p>Development for UWP requires a Microsoft Windows development host. The minimum version supported is Windows 10.</p>
<p>Qt supports UWP apps running on any variant of Windows 10 or later on the desktop PC, IoT, Xbox One, and so on.</p>
<p>If you are targeting a remote device, follow the instructions by Visual Studio to set it up correctly.</p>
<a name="getting-started"></a>
<h2 id="getting-started">Getting Started</h2>
<a name="notes-to-desktop-users"></a>
<h3 id="notes-to-desktop-users">Notes to Desktop Users</h3>
<p>As UWP applications run in a sandboxed environment, some restrictions should be taken into account when considering porting or writing cross-platform applications:</p>
<ul>
<li>The class <a href="../qtcore/qprocess.html">QProcess</a> is not implemented (indicated by the macro <code>QT_NO_PROCESS</code> being defined) as no subprocesses can be launched.</li>
<li>Some paths returned by <a href="../qtcore/qstandardpaths.html#writableLocation">QStandardPaths::writableLocation</a>() may be empty.</li>
<li>A UWP application may not do socket-based communication with another application running on the same host (as this would violate the sandboxing).</li>
<li>Applications run in fullscreen mode only (see <a href="../qtgui/qstylehints.html">QStyleHints</a>). On desktop, the screen size varies as the application is resized.</li>
<li>There are no environment variables. Qt emulates the functionality by maintaining the values locally, so that <a href="../qtcore/qtglobal.html#qputenv">qputenv</a>() and related functions continue to work. All known variables influencing Qt can be set in source code.</li>
<li>UWP applications are UI applications by nature. This implies that console type applications will have a window created internally, which is always visible.</li>
<li>Applications should not exit programmatically. In particular, calling exit() before the UI is shown causes a crash.</li>
<li>The UWP clipboard is local to the application; it cannot be retrieved by a desktop application.</li>
</ul>
<a name="building-applications"></a>
<h3 id="building-applications">Building Applications</h3>
<p>You can develop applications for UWP just as any other Qt applications. Use your favorite editor or IDE (such as Qt Creator) and create your application or load a Qt example. Then run <code>qmake</code> and <code>nmake/jom</code> to build your application.</p>
<a name="building-applications-with-visual-studio"></a>
<h4 id="building-applications-with-visual-studio">Building Applications with Visual Studio</h4>
<p>To launch your project with Visual Studio a corresponding project needs to be created. <code>qmake</code> supports converting a <code>.pro</code> project into Visual Studio format by passing the parameters <code>-tp</code> vc.</p>
<pre class="cpp">

  qmake <span class="operator">-</span>tp vc <span class="operator">&lt;</span>your project<span class="operator">&gt;</span><span class="operator">.</span>pro

</pre>
<p>Be aware of using the correct match of <code>qmake</code> and Visual Studio. As the Visual Studio format is generic, it does not return an immediate error if for instance you open a Windows Phone project inside Visual Studio for Windows.</p>
<p>This creates a project which supports building applications and running them with Visual Studio. It does not embed Qt libraries into the package and requires you to add them manually. For this purpose, the command line tool <a href="windows-deployment.html#the-windows-deployment-tool">windeployqt</a> has been included in the installed package. To enable automatic parsing of dependencies and adding the libraries and dependencies into the application package, create the project with the following options:</p>
<pre class="cpp">

  qmake <span class="operator">-</span>tp vc <span class="operator">&lt;</span>your project<span class="operator">&gt;</span><span class="operator">.</span>pro <span class="string">&quot;CONFIG+=windeployqt&quot;</span>

</pre>
<a name="building-applications-with-qt-creator"></a>
<h4 id="building-applications-with-qt-creator">Building Applications with Qt Creator</h4>
<p>You will not need to do any conversion to open your project in Qt Creator. Please follow the generic instructions on how to open and build a project.</p>
<p>Qt Creator deploys your application on the UWP device, if the device is detected by the PC.</p>
<p><b>Note: </b>Remote PCs, such as the Surface, are not yet supported for deployment by Creator.</p><a name="building-from-source"></a>
<h2 id="building-from-source">Building from Source</h2>
<p>We assume that you have cloned the Qt 5 repositories (or obtained the Qt sources elsewhere) and followed the platform-independent requirements for building Qt. The process of building Qt is found in the <a href="build-sources.html">Building Qt Sources</a> page.</p>
<p>Qt for UWP is always built as a cross-build, because tools, such as qmake, are built as desktop applications. For compiling those, a desktop development environment is required. If you have installed Visual Studio for Windows, this will only create binaries for UWP. You will need Visual Studio for Windows Desktop as well to create those desktop tools.</p>
<p>Please make sure to use an x86 command prompt (either use the <i>VS x86 Native Tools Command Prompt</i> or call <i>vcvarsall.bat</i> without any parameter or with <code>x86</code>) for every UWP build. While the toolchain which is used for the target is set automatically, the command prompt decides what will be used for the host tools like <i>qmake</i> or <i>moc</i>. Building these tools might fail if another command prompt is used.</p>
<p>The UWP mkspec format is <code>&lt;platform&gt;-&lt;architecture&gt;-&lt;toolchain&gt;</code> where architecture can be <code>arm</code>, <code>x86</code>, or <code>x64</code>. The following is an example of building qtbase for UWP:</p>
<pre class="cpp">

  <span class="operator">&gt;</span> <span class="operator">.</span><span class="operator">/</span>configure <span class="operator">-</span>xplatform winrt<span class="operator">-</span>x64<span class="operator">-</span>msvc2017 <span class="operator">-</span>release
  <span class="operator">&gt;</span> nmake<span class="operator">/</span>jom

</pre>
<a name="running-applications-from-command-line"></a>
<h2 id="running-applications-from-command-line">Running Applications from Command Line</h2>
<p>UWP applications must be packaged (including all dependencies) and installed or registered with the application service in order to be launched. <a href="winrt-support.html#winrtrunner">The WinRT Runner Tool</a> can be used to launch these applications from the command line.</p>
<a name="package-content"></a>
<h3 id="package-content">Package Content</h3>
<p>Package content consists of the application executable and its dependencies, as for every Windows application. The dependencies are the needed (Qt) libraries and plugins. Note that Qt plugins have to be put into a folder named after their category (platforms, imageformats, and so on) without using a <code>plugins</code> folder as root. For more information, see <a href="windows-deployment.html">Qt for Windows - Deployment</a>.</p>
<p>As UWP applications are run in a sandboxed environment, setting the path variable to point to the files required will not work.</p>
<p>The <a href="windows-deployment.html#the-windows-deployment-tool">windeployqt</a> convenience tool looks up the application's dependencies and copies Qt libraries and plugins to the appropriate directories, as necessary.</p>
<p>Because all resources are placed to one directory, you can register the directory using an XML file (AppxManifest.xml) and Windows Powershell. The reference for these manifest files can be found <a href="http://msdn.microsoft.com/en-us/library/windows/apps/br211473.aspx">here</a>. The target processor architecture must be specified (as opposed to the default, 'neutral'). As soon as these requirements are met, change into your <i>packaged</i> directory in PowerShell and call:</p>
<pre class="cpp">

  <span class="operator">&gt;</span> Add<span class="operator">-</span>AppxPackage <span class="operator">-</span>Register AppxManifest<span class="operator">.</span>xml

</pre>
<p><b>Note: </b><a href="winrt-support.html#winrtrunner">The WinRT Runner Tool</a> can perform the same operation with the --install option.</p><p>If that worked, you should be able to find your application in Windows' start screen. To remove your application, use Windows' built-in way to uninstall applications (right-click or tap and hold the application and choose <code>Uninstall</code>).</p>
<p><b>Note: </b><a href="winrt-support.html#winrtrunner">The WinRT Runner Tool</a> can perform the same operation with the --remove option.</p><a name="winrt-runner-tool"></a>
<h3 id="winrt-runner-tool">WinRT Runner Tool</h3>
<a name="winrtrunner"></a><p>The WinRT Runner Tool can be found in QTDIR/bin/winrtrunner. It is intended to aid in the deployment, launching, and debugging of Qt for WinRT applications. It can be used from the command line, or invoked by the IDE.</p>
<pre class="cpp plain">

  Usage: winrtrunner [options] package [arguments]
  winrtrunner installs, runs, and collects test results for packages made with Qt.

  Options:
    --test                            Install, start, collect output, stop (if
                                      needed), and uninstall the package. This is
                                      the default action of winrtrunner.
    --start                           Start the package. The package is installed
                                      if it is not already installed. Pass
                                      --install to force reinstallation.
    --debug &lt;debugger&gt;                Start the package with the debugger
                                      attached. The package is installed if it is
                                      not already installed. Pass --install to
                                      force reinstallation.
    --debugger-arguments &lt;arguments&gt;  Arguments that are passed to the debugger
                                      when --debug is used. If no debugger was
                                      provided this option is ignored.
    --suspend                         Suspend a running package. When combined
                                      with --stop or --test, the app will be
                                      suspended before being terminated.
    --stop                            Terminate a running package. Can be be
                                      combined with --start and --suspend.
    --wait &lt;seconds&gt;                  If the package is running, waits the given
                                      number of seconds before continuing to the
                                      next task. Passing 0 causes the runner to
                                      wait indefinitely.
    --install                         (Re)installs the package.
    --remove                          Uninstalls the package.
    --device &lt;name|index&gt;             Specifies the device to target as a device
                                      name or index. Use --list-devices to find
                                      available devices. The default device is the
                                      first device found for the active run
                                      profile.
    --profile &lt;name&gt;                  Force a particular run profile.
    --list-devices                    List the available devices (for use with
                                      --device).
    --verbose &lt;level&gt;                 The verbosity level of the message output
                                      (0 - silent, 1 - info, 2 - debug). Defaults
                                      to 1.
    --ignore-errors                   Always exit with code 0, regardless of the
                                      error state.
    --loopbackexempt &lt;mode&gt;           Enables localhost communication for
                                      clients,servers or both. Adding this
                                      possibility for servers needs elevated
                                      rights and might ask for these in a
                                      dialog.Possible values: client, server,
                                      clientserver
    -?, -h, --help                    Displays this help.

  Arguments:
    package [arguments]               The executable or package manifest to act
                                      upon. Arguments after the package name will
                                      be passed to the application when it starts.

</pre>
</div>
<!-- @@@winrt_support.html -->
        </div>
       </div>
   </div>
   </div>
</div>
<div class="footer">
   <p>
   <acronym title="Copyright">&copy;</acronym> 2020 The Qt Company Ltd.
   Documentation contributions included herein are the copyrights of
   their respective owners.<br/>    The documentation provided herein is licensed under the terms of the    <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation    License version 1.3</a> as published by the Free Software Foundation.<br/>    Qt and respective logos are trademarks of The Qt Company Ltd.     in Finland and/or other countries worldwide. All other trademarks are property
   of their respective owners. </p>
</div>
</body>
</html>
